🎖️GitЯра🎖️
docs/packet_format.md 9f73fbf87002682ba3c1f3da32b7252d8ea2feda (9f73fbf8) Text, 8.83 KB
Tc9d1d9# Packet Format
This document describes the MeshCore packet format.
Tff7b72- Ta5d6ff`0xYY` indicates Ta5d6ff`YY` in hex notation.
Tff7b72- Ta5d6ff`0bYY` indicates Ta5d6ff`YY` in binary notation.
Tff7b72- Bit 0 indicates the bit furthest to the right: Ta5d6ff`0000000X`
Tff7b72- Bit 7 indicates the bit furthest to the left: Ta5d6ff`X0000000`
Tc9d1d9## Version 1 Packet Format
This is the protocol level packet structure used in MeshCore firmware v1.12.0
Ta5d6ff```
[header][transport_codes(optional)][path_length][path][payload]
```
Tff7b72- [Tff7b72header](Te6edf3#header-format) - 1 byte
Tff7b72- 8-bit Format: Ta5d6ff`0bVVPPPPRR` - Ta5d6ff`V=Version` - Ta5d6ff`P=PayloadType` - Ta5d6ff`R=RouteType`
Tff7b72- Bits 0-1 - 2-bits - [Tff7b72Route Type](Te6edf3#route-types)
Tff7b72- Ta5d6ff`0x00`/Ta5d6ff`0b00` - Ta5d6ff`ROUTE_TYPE_TRANSPORT_FLOOD` - Flood Routing + Transport Codes
Tff7b72- Ta5d6ff`0x01`/Ta5d6ff`0b01` - Ta5d6ff`ROUTE_TYPE_FLOOD` - Flood Routing
Tff7b72- Ta5d6ff`0x02`/Ta5d6ff`0b10` - Ta5d6ff`ROUTE_TYPE_DIRECT` - Direct Routing
Tff7b72- Ta5d6ff`0x03`/Ta5d6ff`0b11` - Ta5d6ff`ROUTE_TYPE_TRANSPORT_DIRECT` - Direct Routing + Transport Codes
Tff7b72- Bits 2-5 - 4-bits - [Tff7b72Payload Type](Te6edf3#payload-types)
Tff7b72- Ta5d6ff`0x00`/Ta5d6ff`0b0000` - Ta5d6ff`PAYLOAD_TYPE_REQ` - Request (destination/source hashes + MAC)
Tff7b72- Ta5d6ff`0x01`/Ta5d6ff`0b0001` - Ta5d6ff`PAYLOAD_TYPE_RESPONSE` - Response to Ta5d6ff`REQ` or Ta5d6ff`ANON_REQ`
Tff7b72- Ta5d6ff`0x02`/Ta5d6ff`0b0010` - Ta5d6ff`PAYLOAD_TYPE_TXT_MSG` - Plain text message
Tff7b72- Ta5d6ff`0x03`/Ta5d6ff`0b0011` - Ta5d6ff`PAYLOAD_TYPE_ACK` - Acknowledgment
Tff7b72- Ta5d6ff`0x04`/Ta5d6ff`0b0100` - Ta5d6ff`PAYLOAD_TYPE_ADVERT` - Node advertisement
Tff7b72- Ta5d6ff`0x05`/Ta5d6ff`0b0101` - Ta5d6ff`PAYLOAD_TYPE_GRP_TXT` - Group text message (unverified)
Tff7b72- Ta5d6ff`0x06`/Ta5d6ff`0b0110` - Ta5d6ff`PAYLOAD_TYPE_GRP_DATA` - Group datagram (unverified)
Tff7b72- Ta5d6ff`0x07`/Ta5d6ff`0b0111` - Ta5d6ff`PAYLOAD_TYPE_ANON_REQ` - Anonymous request
Tff7b72- Ta5d6ff`0x08`/Ta5d6ff`0b1000` - Ta5d6ff`PAYLOAD_TYPE_PATH` - Returned path
Tff7b72- Ta5d6ff`0x09`/Ta5d6ff`0b1001` - Ta5d6ff`PAYLOAD_TYPE_TRACE` - Trace a path, collecting SNR for each hop
Tff7b72- Ta5d6ff`0x0A`/Ta5d6ff`0b1010` - Ta5d6ff`PAYLOAD_TYPE_MULTIPART` - Packet is part of a sequence of packets
Tff7b72- Ta5d6ff`0x0B`/Ta5d6ff`0b1011` - Ta5d6ff`PAYLOAD_TYPE_CONTROL` - Control packet data (unencrypted)
Tff7b72- Ta5d6ff`0x0C`/Ta5d6ff`0b1100` - reserved
Tff7b72- Ta5d6ff`0x0D`/Ta5d6ff`0b1101` - reserved
Tff7b72- Ta5d6ff`0x0E`/Ta5d6ff`0b1110` - reserved
Tff7b72- Ta5d6ff`0x0F`/Ta5d6ff`0b1111` - Ta5d6ff`PAYLOAD_TYPE_RAW_CUSTOM` - Custom packet (raw bytes, custom encryption)
Tff7b72- Bits 6-7 - 2-bits - [Tff7b72Payload Version](Te6edf3#payload-versions)
Tff7b72- Ta5d6ff`0x00`/Ta5d6ff`0b00` - v1 - 1-byte src/dest hashes, 2-byte MAC
Tff7b72- Ta5d6ff`0x01`/Ta5d6ff`0b01` - v2 - Future version (e.g., 2-byte hashes, 4-byte MAC)
Tff7b72- Ta5d6ff`0x02`/Ta5d6ff`0b10` - v3 - Future version
Tff7b72- Ta5d6ff`0x03`/Ta5d6ff`0b11` - v4 - Future version
Tff7b72- Ta5d6ff`transport_codes` - 4 bytes (optional)
Tff7b72- Only present for Ta5d6ff`ROUTE_TYPE_TRANSPORT_FLOOD` and Ta5d6ff`ROUTE_TYPE_TRANSPORT_DIRECT`
Tff7b72- Ta5d6ff`transport_code_1` - 2 bytes - Ta5d6ff`uint16_t` - calculated from region scope
Tff7b72- Ta5d6ff`transport_code_2` - 2 bytes - Ta5d6ff`uint16_t` - reserved
Tff7b72- Ta5d6ff`path_length` - 1 byte - Encoded path metadata
Tff7b72- Bits 0-5 store path hash count / hop count (Ta5d6ff`0-63`)
Tff7b72- Bits 6-7 store path hash size minus 1
Tff7b72- Ta5d6ff`0b00`: 1-byte path hashes
Tff7b72- Ta5d6ff`0b01`: 2-byte path hashes
Tff7b72- Ta5d6ff`0b10`: 3-byte path hashes
Tff7b72- Ta5d6ff`0b11`: reserved / unsupported
Tff7b72- Ta5d6ff`path` - Ta5d6ff`hop_count * hash_size` bytes - Path to use for Direct Routing or flood path tracking
Tff7b72- Up to a maximum of 64 bytes, defined by Ta5d6ff`MAX_PATH_SIZE`
Tff7b72- Effective byte length is calculated from the encoded hop count and hash size, not taken directly from Ta5d6ff`path_length`
Tff7b72- v1.12.0 firmware and older only handled legacy 1-byte path hashes and dropped packets whose path bytes exceeded [Tff7b7264 bytes](Te6edf3https://github.com/meshcore-dev/MeshCore/blob/e812632235274ffd2382adf5354168aec765d416/src/Dispatcher.cpp#L144)
Tff7b72- Ta5d6ff`payload` - variable length - Payload Data
Tff7b72- Up to a maximum 184 bytes, defined by Ta5d6ff`MAX_PACKET_PAYLOAD`
Tff7b72- Generally this is the remainder of the raw packet data
Tff7b72- The firmware parses this data based on the provided Payload Type
Tff7b72- v1.12.0 firmware and older drops packets with Ta5d6ff`payload` sizes [Tff7b72larger than 184](Te6edf3https://github.com/meshcore-dev/MeshCore/blob/e812632235274ffd2382adf5354168aec765d416/src/Dispatcher.cpp#L152)
Tc9d1d9### Packet Format
| Field | Size (bytes) | Description |
|-----------------|----------------------------------|-----------------------------------------------------------------|
| header | 1 | Contains routing type, payload type, and payload version |
| transport_codes | 4 (optional) | 2x 16-bit transport codes (if ROUTE_TYPE_TRANSPORT_*) |
| path_length | 1 | Encodes path hash size in bits 6-7 and hop count in bits 0-5 |
| path | up to 64 (Ta5d6ff`MAX_PATH_SIZE`) | Stores Ta5d6ff`hop_count * hash_size` bytes of path data if applicable |
| payload | up to 184 (Ta5d6ff`MAX_PACKET_PAYLOAD`) | Data for the provided Payload Type |
Tff7b72> NOTE: see the [Payloads](./payloads.md) documentation for more information about the content of specific payload types.
Tc9d1d9### Header Format
Bit 0 means the lowest bit (1s place)
| Bits | Mask | Field | Description |
|------|--------|-----------------|----------------------------------|
| 0-1 | Ta5d6ff`0x03` | Route Type | Flood, Direct, etc |
| 2-5 | Ta5d6ff`0x3C` | Payload Type | Request, Response, ACK, etc |
| 6-7 | Ta5d6ff`0xC0` | Payload Version | Versioning of the payload format |
Tc9d1d9### Route Types
| Value | Name | Description |
|--------|-------------------------------|----------------------------------|
| Ta5d6ff`0x00` | Ta5d6ff`ROUTE_TYPE_TRANSPORT_FLOOD` | Flood Routing + Transport Codes |
| Ta5d6ff`0x01` | Ta5d6ff`ROUTE_TYPE_FLOOD` | Flood Routing |
| Ta5d6ff`0x02` | Ta5d6ff`ROUTE_TYPE_DIRECT` | Direct Routing |
| Ta5d6ff`0x03` | Ta5d6ff`ROUTE_TYPE_TRANSPORT_DIRECT` | Direct Routing + Transport Codes |
Tc9d1d9### Path Length Encoding
Ta5d6ff`path_length` is not a raw byte count. It packs both hash size and hop count:
| Bits | Field | Meaning |
|------|----------------|--------------------------------|
| 0-5 | Hop Count | Number of path hashes (Ta5d6ff`0-63`) |
| 6-7 | Hash Size Code | Stored as Ta5d6ff`hash_size - 1` |
Hash size codes:
| Bits 6-7 | Hash Size | Notes |
|----------|-----------|-------------------------------|
| Ta5d6ff`0b00` | 1 byte | Legacy / default mode |
| Ta5d6ff`0b01` | 2 bytes | Supported in current firmware |
| Ta5d6ff`0b10` | 3 bytes | Supported in current firmware |
| Ta5d6ff`0b11` | 4 bytes | Reserved / invalid |
Examples:
Tff7b72- Ta5d6ff`0x00`: zero-hop packet, no path bytes
Tff7b72- Ta5d6ff`0x05`: 5 hops using 1-byte hashes, so path is 5 bytes
Tff7b72- Ta5d6ff`0x45`: 5 hops using 2-byte hashes, so path is 10 bytes
Tff7b72- Ta5d6ff`0x8A`: 10 hops using 3-byte hashes, so path is 30 bytes
Tc9d1d9### Payload Types
| Value | Name | Description |
|--------|---------------------------|----------------------------------------------|
| Ta5d6ff`0x00` | Ta5d6ff`PAYLOAD_TYPE_REQ` | Request (destination/source hashes + MAC) |
| Ta5d6ff`0x01` | Ta5d6ff`PAYLOAD_TYPE_RESPONSE` | Response to Ta5d6ff`REQ` or Ta5d6ff`ANON_REQ` |
| Ta5d6ff`0x02` | Ta5d6ff`PAYLOAD_TYPE_TXT_MSG` | Plain text message |
| Ta5d6ff`0x03` | Ta5d6ff`PAYLOAD_TYPE_ACK` | Acknowledgment |
| Ta5d6ff`0x04` | Ta5d6ff`PAYLOAD_TYPE_ADVERT` | Node advertisement |
| Ta5d6ff`0x05` | Ta5d6ff`PAYLOAD_TYPE_GRP_TXT` | Group text message (unverified) |
| Ta5d6ff`0x06` | Ta5d6ff`PAYLOAD_TYPE_GRP_DATA` | Group datagram (unverified) |
| Ta5d6ff`0x07` | Ta5d6ff`PAYLOAD_TYPE_ANON_REQ` | Anonymous request |
| Ta5d6ff`0x08` | Ta5d6ff`PAYLOAD_TYPE_PATH` | Returned path |
| Ta5d6ff`0x09` | Ta5d6ff`PAYLOAD_TYPE_TRACE` | Trace a path, collecting SNR for each hop |
| Ta5d6ff`0x0A` | Ta5d6ff`PAYLOAD_TYPE_MULTIPART` | Packet is part of a sequence of packets |
| Ta5d6ff`0x0B` | Ta5d6ff`PAYLOAD_TYPE_CONTROL` | Control packet data (unencrypted) |
| Ta5d6ff`0x0C` | reserved | reserved |
| Ta5d6ff`0x0D` | reserved | reserved |
| Ta5d6ff`0x0E` | reserved | reserved |
| Ta5d6ff`0x0F` | Ta5d6ff`PAYLOAD_TYPE_RAW_CUSTOM` | Custom packet (raw bytes, custom encryption) |
Tc9d1d9### Payload Versions
| Value | Version | Description |
|--------|---------|--------------------------------------------------|
| Ta5d6ff`0x00` | 1 | 1-byte src/dest hashes, 2-byte MAC |
| Ta5d6ff`0x01` | 2 | Future version (e.g., 2-byte hashes, 4-byte MAC) |
| Ta5d6ff`0x02` | 3 | Future version |
| Ta5d6ff`0x03` | 4 | Future version |
Served by rngit 1.5.2 - Generated in 0.18s